SST ShlWAPI StrFromTimeInterval Function

	(SST) ShlWAPI.pas Version 1.08

Developer Reference

(SST)ShlWAPI StrFromTimeInterval Function
Converts an unsigned, 32 bit, integer value into a user friendly text (alt. string) that expresses a time span corresponding to the input value interpreted as a number of milliseconds.

Scope
Global (i.e. this function can be called/accessed from code in any unit that includes/uses (SST)ShlWAPI.pas).

Syntax
	function StrFromTimeInterval(pszOut : LPSTR; cchMax : UINT; dwTimeMS : DWORD; digits : Integer) : Integer;
	function StrFromTimeIntervalA(pszOut : LPSTR; cchMax : UINT; dwTimeMS : DWORD; digits : Integer) : Integer; function StrFromTimeIntervalW(pszOut : LPWSTR; cchMax : UINT; dwTimeMS : DWORD; digits : Integer) : Integer;

Parameters
pszOut [out]	A pointer to the buffer into which the function should write the zero-terminated string, representing the time span equivalent to the specified number of millisecnods.
cchMax [in]	The size, including the terminating null character, in number of characters (single or double byte, depending on which version is being called), of the buffer pointed to by pszOut. If the specified value is less than the number of characters necessary to accommodate the formatted string, the function returns the required buffer size (including the terminating null character).
dwTimeMS [in]	The time span, in number of milliseconds, to format/convert.
digits [in]	The preocision with which the time is formatted.

Return Values
If the value specified in cchMax is large enough for the output string, the function returns the number of characters (single or double byte, depending on which version was called) actually written to the buffer pointed to in pszOut. If the value specified in cchMax is smaller than the length of the zero-terminated, output string, the function returns the length of the string, without writing the string to the buffer. In both cases, the returned value includes the terminating null character (see remarks, below).

Remarks
Contrary to the Microsoft documentation accompanying MS SDK version 6.1, the function returns values that include the terminating null character (at least under Windows Vista with SP 1 and IE 8). Furthermore, it is not necessary, even if it is good practice and less error prone, to specify a zero in cchMax, to retrieve the required buffer size. All values, smaller than the number of output characters calculated by the function, have the same effect.
The function may contain a minor bug, in that it appears to clip the "hr" (and other unit abbreviations/names), instead of merely the number of digits of the numerical value(s), when called with the "digits" parameter set to a value smaller than the length of the (abbreviated) unit name(s) (e.g. "hr", "sec", etc.). The following output, generated under Windows Vista with SP 1 & IE 8, by the code listed further below, exemplifies the issue. StrFromTimeInterval called with 663442253 //buffer size = 7 + 1 and "digits" = 1, 6, 100 h <-- ERROR here (missing "r") StrFromTimeInterval called with 663442253 //buffer size = 14 + 1 and "digits" = 4, 13, 184 hr 10 mi <-- ERROR here (missing "n") StrFromTimeInterval called with 663442253 //buffer size = 21 + 1 and "digits" = 8, 20, 184 hr 17 min 22 se <-- ERROR here (missing "c") One possible cause for this bug may be the not immediately apparent fact, that the string returned by the function has a leading blank/space (e.g. " 100 h", " 184 hr 10 mi"). Another possible explanation is that the function adjusts the number of returned characters according to the available buffer size. However, irrespective of the cause(s), if the buffer size is large enough, the function returns a string with the full length/correct abbreviations (see last two function calls in the example, below).

Remarks

Contrary to the Microsoft documentation accompanying MS SDK version 6.1, the function returns values that include the terminating null character (at least under Windows Vista with SP 1 and IE 8). Furthermore, it is not necessary, even if it is good practice and less error prone, to specify a zero in cchMax, to retrieve the required buffer size. All values, smaller than the number of output characters calculated by the function, have the same effect.

The function may contain a minor bug, in that it appears to clip the "hr" (and other unit abbreviations/names), instead of merely the number of digits of the numerical value(s), when called with the "digits" parameter set to a value smaller than the length of the (abbreviated) unit name(s) (e.g. "hr", "sec", etc.). The following output, generated under Windows Vista with SP 1 & IE 8, by the code listed further below, exemplifies the issue.

StrFromTimeInterval called with 663442253 //buffer size = 7 + 1 and "digits" = 1,
6,  100 h <-- ERROR here (missing "r")
StrFromTimeInterval called with 663442253 //buffer size = 14 + 1 and "digits" = 4,
13,  184 hr 10 mi <-- ERROR here (missing "n")
StrFromTimeInterval called with 663442253 //buffer size = 21 + 1 and "digits" = 8,
20,  184 hr 17 min 22 se <-- ERROR here (missing "c")

One possible cause for this bug may be the not immediately apparent fact, that the string returned by the function has a leading blank/space (e.g. " 100 h", " 184 hr 10 mi"). Another possible explanation is that the function adjusts the number of returned characters according to the available buffer size. However, irrespective of the cause(s), if the buffer size is large enough, the function returns a string with the full length/correct abbreviations (see last two function calls in the example, below).

Example
PROCEDURE TForm4.TestShlWAPIStrFromTimeInterval(Sender : TObject); VAR millisecs : DWORD; VAR timespanstrbufp : PChar; VAR bufsize : UINT; VAR apiretval : INTEGER; VAR newinfoline : STRING; BEGIN millisecs := 0; timespanstrbufp := NIL; apiretval := 0; newinfoline := ''; millisecs := GetTickCount(); //Retrieve the required buffer size bufsize := UINT(StrFromTimeInterval(NIL, 0, millisecs, 1)); timespanstrbufp := StrAlloc(bufsize + 1); newinfoline := 'StrFromTimeInterval called with ' + IntToStr(millisecs); Memo1.Lines.Add(newinfoline); apiretval := StrFromTimeInterval(timespanstrbufp, bufsize, millisecs, 1); newinfoline := timespanstrbufp; newinfoline := IntToStr(apiretval) + ', ' + newinfoline; Memo1.Lines.Add(newinfoline); StrDispose(timespanstrbufp); timespanstrbufp := NIL; //Retrieve the required buffer size bufsize := UINT(StrFromTimeInterval(NIL, 0, millisecs, 4)); timespanstrbufp := StrAlloc(bufsize + 1); newinfoline := 'StrFromTimeInterval called with ' + IntToStr(millisecs); Memo1.Lines.Add(newinfoline); apiretval := StrFromTimeInterval(timespanstrbufp, bufsize, millisecs, 4); newinfoline := timespanstrbufp; newinfoline := IntToStr(apiretval) + ', ' + newinfoline; Memo1.Lines.Add(newinfoline); StrDispose(timespanstrbufp); bufsize := UINT(StrFromTimeInterval(NIL, 0, millisecs, 8)); timespanstrbufp := StrAlloc(bufsize + 1); newinfoline := 'StrFromTimeInterval called with ' + IntToStr(millisecs); Memo1.Lines.Add(newinfoline); apiretval := StrFromTimeInterval(timespanstrbufp, bufsize, millisecs, 8); newinfoline := timespanstrbufp; newinfoline := IntToStr(apiretval) + ', ' + newinfoline; Memo1.Lines.Add(newinfoline); StrDispose(timespanstrbufp); millisecs := GetTickCount(); bufsize := UINT(StrFromTimeInterval(NIL, 0, millisecs, 8)); //Create buffer that makes allowances for the leading blank (i.e. a much too large buffer) bufsize := bufsize + 9; timespanstrbufp := StrAlloc(bufsize); ZeroMemory(timespanstrbufp, bufsize); newinfoline := 'StrFromTimeInterval called with ' + IntToStr(millisecs); Memo1.Lines.Add(newinfoline); apiretval := StrFromTimeInterval(timespanstrbufp, bufsize, millisecs, 8); newinfoline := timespanstrbufp; newinfoline := IntToStr(apiretval) + ', ' + newinfoline; Memo1.Lines.Add(newinfoline); StrDispose(timespanstrbufp); Memo1.Lines.Add(''); END;
Under Windows Vista with SP1 & IE8, the above example produces the following output (obviously, only if called with the same number of milliseconds).
StrFromTimeInterval called with 873563182 6, 200 h StrFromTimeInterval called with 873563182 13, 242 hr 30 mi StrFromTimeInterval called with 873563182 20, 242 hr 39 min 23 se StrFromTimeInterval called with 873563197 21, 242 hr 39 min 23 sec

Requirements
Unit:	Declared and imported in (SST)ShlWAPI.pas
Library:	(SST)ShlWAPI.dcu/(SST)ShlWAPI.obj
Unicode:	Implemented as ANSI (StrFromTimeInterval and StrFromTimeIntervalA) and Unicode (StrFromTimeIntervalW) functions.
Min. ShlWAPI.dll version according to MS SDK doc.:	4.71
Min. ShlWAPI.dll version based on SST research:	4.71
Min. OS version(s) according to Microsoft SDK doc.:	Windows 2000, Windows NT 4.0 with Internet Explorer 4.0, Windows 98, Windows 95 with Internet Explorer 4.0
Min. OS version(s) according to SST research.:	Windows NT 4.0 with IE 4.0, Windows 95 with IE 4.0, Windows 98, Windows 2000 and later